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Abstract: 

The Goddard Earth Observing System version 5 (GEOS-5) General Circulation Model (GCM) 
makes use of the Earth System Modeling Framework (ESMF) to enable model configurations with 
many functions. One of the options of the GEOS-5 GCM is the GEOS-5 Chemistry Transport Model 
(GEOS-5 CTM), which is an offline simulation of chemistry and constituent transport driven by a 
specified meteorology and other model output fields. This document describes the basic components 
of the GEOS-5 CTM, and is a user’s guide on to how to obtain and run simulations on the NCCS 
Discover platform. In addition, we provide information on how to change the model configuration 
input hies to meet users’ needs. 


v 



This page intentionally left blank. 



Contents 


1 Background| 

2 Obtaining the Code 

3 Compiling the code 

4 Running the Code 

5 Changing Default Configuration 

5.1 CTM_GridComp.rc File 

5.2 Duration of Experiment 

5.3 ExtData Component! 

5.4 Ouputting Variables! 

|Bibliography| 

Appendix A: Meteorological Fields for GMI 

|Appendix B: Using the GEOS-5 CTM CC for Producing Diagnostics 
Appendix C: Export State Variables 


3.1 

pCHEM . 

|3.2 

GMTI . . . 

|3.3 

GoCArtI 


1 

1 

2 

2 

3 

3 

4 

4 

5 

5 

8 

8 

10 

10 

10 

13 

vii 


This page intentionally left blank. 



1 Background 


The GEOS-5 Chemistry Transport Model (CTM) integrates one configurable CTM with options for 
running any chemistry module currently available within the GEOS-5 GCM code base. It uses the 
GEOS-5 Earth System Modeling Framework (ESMF) infrastructure (MAPL, the "History" com- 
ponent and the "ExtData" component) and the GEOS-5 advection component (AdvCore) to drive 
the GEOS-5 Chemistry component (that includes options for the Global Modeling Initiative (GMI) 

| Logan et a h, 2003] , the Global Ozone Chemistry Aerosol Radiation and Transport (GOCART) 
|Chin et al., 2000 , GEOS-Chem |Bey et al., 2001 1 , etc.). Detailed information about the GEOS-5 
CTM is available in |Kouatchou et al., 2015| . 

The main components of GEOS-5 CTM are: 


AdvCore : the transport conrponet which source code is part of the GEOS-5 directory FVdycore- 
Cubed_ GridComp/. 

Chemistry : the GEOS-5 Chemistry component which contains all the options for chemistry mod- 
els available in GEOS-5 GCM, such as GOCART, GMI, GEOS-Chem, etc. The entire GEOS-5 
GEOSchem_ GridComp/ defines this component. 

Diffusion : component where various diffusion methods are implemented. 


Convection : component where various convection methods are implemented. 


GEOS-5 CTM Cinderella : a component which primary role is to provide services to the other 
components. For instance, it will compute the courant numbers and mass fluxes (using the 
winds and pressure) for AdvCore. 

They are shown in Figure [lj 



Figure 1: Flow diagram of the main components of GEOS-5 CTM. 


2 Obtaining the Code 

It is assumed that we have access to the GEOS-5 CVS repository and that we have the settings: 

setenv CVS_RSH ssh 

setenv CVSR00T : ext :userID@progressdirect .nccs .nasa.gov: /cvsroot/esma 
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where userlD is our NCOS username. 

The latest version of GEOS-5 CTM (as of August 2015) is under the tag name: 

Heracles-3_1_CTM 

To obtain the code, use the cvs command: 

cvs co -r Heracles-3_ 1_ CTM GEOSctm 

We will then get the directory GEOSctm/. The basic directory structure of the code is: 
src/ 

src/Conf ig/ 
src/GMAO_Shared/ 
src/Appli cat ions/ 
src/Applications/GEOSctm_App 
src/GEOSctm_GridComp/ 

src/GEOSctm_GridComp/CTMconvection_GridComp/ 
src/GEOSctm_GridComp/CTMdif fusion_GridComp/ 
src/GEOSctm_GridComp/CTMpTracers_GridComp/ 
src/GEOSctm_GridComp/FVdycoreCubed_GridComp/ 
src/GEOSctm_GridComp/GEOSchem_GridComp/ 

The GEOS-5 CTM Cinderella component (used to derived variables) is included in the file: 

src/GEOSctm_GridComp/GEOS_ctmEnvGridComp . F90 


3 Compiling the code 

To compile the code, go to the directory: 

GEOSctm/src/ 

and issue the command (that does a parallel compilation): 

,/parallel_ build, csh 

(we should be ready to provide our sponsor code account). The executable, GEOSctm. x, will be in 
the directory: 

GEOSctm/LiniLx/bin 


4 Running the Code 

In order to run GEOS-5 CTM, a "setup" script is available with a suite of default configurations. 
Go to the directory GEOSctm/src/ Applications/ GEOSctm_App/ and run the script: 

./ctm_ setup 

We will answer a series of questions to determine the model configuration (horizontal resolution, type 
of Chemistry, driving dataset, etc.) we are interested in. Table [I] shows the possible configuration 
options. 

The script will automatically generate configuration files and run scripts. In our experiment direc- 
tory, it will create: 
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Chemistry 

Passive Tracer, pChem, GOCART, GMI, GOCART Data 

Driving Dataset 

MERRA, FP, FP-IT, MERRA2 

Horizontal Resolution (deg) 

2, 1, 1/2, 1/4, 1/8, 1/16 


Table 1: Configuration options of GEOS-5 CTM. 


CAP . rc : 


HISTORY. rc: 
ctm_run . j : 

RC/ 

CTM_GridComp . rc : 


GEOSCTM . rc : 
MAPL_ExtData. rc 


file containing information on start date & time, 

end date & time of job segment, duration of job 

segment, stop date & time of entire experiment. 

file for selecting the type of diagnostics to be produced 

SLURM script for submitting the job 

contains all the resource files needed to drive the model 

file for turning on/off Convection, Diffusion 

and for selecting the type of meteorological 

driving (MERRA or MERRA2) 

file for setting model parameters 

file needed by ExtData to read external data files 


Before submitting, create the file: 


cap_restart : ASCII file containing (single line) starting the 

date (YYYYMMDD) and time (HHMMSS) of the job segment 
in the format: YYYYMMDD HHMMSS 


and then issue the command: 


qsub ctm_ run.j 

At run time, the following directories will be created: 

holding/: location where output files are moved to after a 

successful run. 

restart/: location of restart files generated by the model 

scratch/: temporary directory used to keep necessary files 

while the code is running 

Remark 1 If we choose to use MERRA2 driving datasets (default option), the ctm_setup script 
will generate the file MERRA2_ExtData.rc.tmpl instead of MAPL_ExtData.rc. At run time, 
the SLURM script ctm_run.j manipulates MERRA2_ExtData.rc.tmpl to create a file similar to 
MAPL_ExtData.rc. 

5 Changing Default Configuration 

5.1 CTM_GridComp.rc File 

The CTM_ GridComp.rc file is used to set options for Convection, Diffusion and the type meteoro- 
logical data. 

Meteorological Data 

We need to set the variable metType that has two options: MERRA 2 (default, can also be used for 
FP-IT data) and MERRA (for MERRA data). 
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Convection 


By default, Convection is activated for GMI and not for other configurations. In case we want to 
exercise Convection for non- GMI experiments, we need to set: 

do_ctmConvection: T 

convecType: 1 # convective transport only 


Diffusion 

By default, Duffusion is activated all configurations but Passive Tracer. In case we want to exercise 
Diffusion, we need to set: 

do_ctmDif fusion: T 

5.2 Duration of Experiment 

In the process of generating the configuration scripts, the following files were created: 

• CAP.rc: contains begin/end date and time of entire job, stop date, duration (in days) of each 
job segment. 

• ctm_run.j : SLURM script 

• cap_restart: contains two numbers pointing to the starting date YYYYMMDD and starting 
hour HHMMSS of the job. 

Assume that we want to carry out a 12-month experiment with January 1, 2005 as starting date. 
We want to run one month at the time. The file cap_ restart will have 

20050101 000000 

and the file CAP.rc will have the settings: 

BEG_DATE: 20000101 000000 

END_DATE: 20060101 000000 

J0B_SGMT : 00000031 000000 

Note that the stop date END DATE is January 1, 2006. We will need to submit the PBS script: 

qsub ctm_ run.j 

When the first job segment is completed (for January 2005), the script will resubmit itself. The file 
cap_ restart will automatically be updated to contain 

20050201 000000 

5.3 ExtData Component 

GEOS-5 contains the Gridded Component ExtData that has the ability to read from external files 
variables needed by the model. ExtData 

• Relies on a resource file that lists the variables to be read in. Each variable is represented with 
the following information: short name, dimension, unit, path to netCDF /hdf file containing 
the variable, variable name in the hie, reading frequency, etc. 

• Can perform unit conversion. It has basic scaling and offset calculations. 
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• Does time interpolation. 

• Does regridding. 

• Is called at every time step before all the other run methods (Physics, Dynamics). 

• Is the last ESMF gridded component the entire code will rely on to look for the availability 
of a given variable (requested by another ESMF gridded component). If the variable cannot 
be provided, the code will abort. 


Create/Edit the file MAPLExtData.rc: 

This resource hie (to be located in the running directory) is read by the ExtData component and 
should contain information on the variables to be extracted from the hies. 


PrimaryExports : 
# 1 ___ 

# Export 1 

# Name I 

# 1 __ 


-1— 1 

1 1 

V 

| 1 _. 

1 1 


-1 1 

1 

1 


Units 

1 Dim | 
- 1 1 

Loc 

1 Clim | 

| |- 

Time Template 

I Offset 
-1 

1 Scale 
| 

1 Variable 

| 

1 Template 

_| 

ZPBL 

’m’ 

xy 

C 

N 

N 

0 

0.0 

1.0 

PBLH 

MERRA2.400 . tavgl_2d_f lx_Nx . 0 /,y4%m2°/.d2 . nc4 

FRLAND 

’1’ 

xy 

C 

Y 

N 

0 

0.0 

1.0 

FRLAND 

MERRA2_400 . const_2d_asm_Nx . climatology . nc4 

T 

’K’ 

xyz 

C 

N 

N 

0 

0.0 

1.0 

T 

MERRA2_400 . inst3_3d_asm_Nv . %y4%m2 0 / 0 d2 . nc4 

PLE 

’Pa’ 

xyz 

E 

N 

N 

0 

0.0 

1.0 

PLE 

MERRA2_400 . tavg3_3d_nav_Ne . %y4%n2 0 / 0 d2 . nc4 


where: 


Export Name: The variable name as written in Import State declaration. 


Units: The unit of the variable. 


Dim: Variable dimension (xy or xyz) 


V Loc: Can have either ’C’ (center) of ’E’ (edge). 


Clim: Determine if the reading will be cyclic (Y) or not (N). 


Factors: Offset and Scale for unit vo inversion. 


External File: The variable name as it appears in the hie and the location where the external hie 
resides. 


5.4 Ouputting Variables 
Component Names 

To produce a held by the HISTORY component, it is important to know the acronym of the 
component which owns it. Table [2] lists the main component names and their acronyms. 

HISTORY Settings 

The contents of the the hie HISTORY. rc tell the model what and how to output its state and 
diagnostic helds. To learn the proper settings in HISTORY. rc, visit the website: 


http:/ /geos5.org/wiki/index.php?title=Ganymed_4.1_User’s_Guide/^Determining_Output:_HISTORY.rc 
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Long Name 

Name in HISTORY. rc 

GEOS-5 CTM Cinderella 

CTMenv 

GEOSchem Cinderella 

CHEMENV 

Passive Tracer 

TR 

GOCART 

GOCART 

GMI 

GMICHEM 

Convection 

CONVECTION 

Diffusion 

DIFFUSION 


Table 2: Component Names and Acronymes Used in HISTORY. rc. 
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Appendix A: Meteorological Fields for GMI 

Below is a the list of typical meteorological related variables required to run the GMI configuration. 


Short Name 

Long Name 

Unit 

AIRDENS 

air density 

kg m-3 

ALBVF 

surface albedo for visible diffuse 

1 

ASNOW 

fractional area of land snowcover 

1 

CLDTT 

total cloud area fraction 

1 

CN_PRCP 

convective precipitation 

kg m-2 s - 1 

CNV_MFC 

cumulative mass flux 

kg m-2 s - 1 

CNV_MFD 

detraining mass flux 

kg m-2 s - 1 

DFPAR 

surface downwelling par diffuse flux 

W m-2 

DQDT 

specific humidity tendency due to moist 

s - 1 

DRPAR 

surface downwelling par beam flux 

W m-2 

FOLD 

cloud fraction for radiation 

1 

FRACI 

ice covered fraction of tile 

1 

FRLAKE 

fraction of lake 

1 

FRLAND 

fraction of land 

1 

FRLANDICE 

fracrion of land-ice 

1 

GRN 

greeness fraction 

1 

LAI 

leaf area index 

1 

LFR 

lightning flash rate 

km-2 s-1 

LWI 

land-ocean-ice mask 

1 

PFL_CN 

3D flux of liquid convective precipitation 

kg m-2 s-1 

PFL_LSAN 

3D flux of liquid non convective precipitation 

kg m-2 s-1 

PLE 

air pressure 

Pa 

PS 

surface pressure 

Pa 

Q 

specific humidity 

1 

QL 

cloud liquid for radiation 

1 

RH2 

relative humidity after moist 

1 

SWNDSRF 

surface net downward shortwave flux 

W m-2 

T 

temperature 

K 

T2M 

2-meter air temperature 

K 

TA 

surface air temperature 

K 

TAUCLW 

optical thickness for liquid clouds 

1 

TAUCLI 

optical thickness for ice clouds 

1 

TPREC 

total precipitation 

kg m-2 s-1 

TROPP 

tropopause pressure based on blended estimate 

Pa 

U 

eastward wind 

m s-1 

U10M 

10-meter eastward wind 

m s-1 

USTAR 

surface velocity scale 

m s-1 

V 

northward wind 

m s-1 

V10M 

10-meter northward wind 

m s-1 

WET1 

surface soil wetness 

1 

ZOH 

surface roughness for heat 

m 

ZPBL 

Planetary boundary layer height 

m 

ZLE 

geopotential height 

m 


Appendix B: Using the GEOS-5 CTM CC for Producing Diagnostics 

The GEOS-5 CTM Cinderella component (CC) can be used to produce diagnostics variables. Users 
may want the model to output meteorological fields (that are in external data hies) at the same 



resolution as that of the other diagnostics. Simple code modifications can be done in CC to achieve 
it. Assume that we want to write out specific humidity. The following changes will be introduced 
in CC: 

SetServices 


call MAPL_AddImportSpec (GC, & 

SHORT_NAME = ’ Q ’ , & 

L0NG_NAME = ’specif ic_humidity’ , & 

UNITS = ’kg kg- 1 ’ , & 

DIMS = MAPL_DimsHorzVert , & 

VLOCATION = MAPL_VLocationCenter , RC=STATUS ) 

VERIFY, (STATUS) 

call MAPL_AddExportSpec (GC, & 

SHORT_NAME = ’ Q ’ , & 

L0NG_NAME = ’specif ic_humidity ’ , & 

UNITS = ’kg kg- 1 ’ , & 

DIMS = MAPL_DimsHorzVert , & 

VLOCATION = MAPL_VLocationCenter , RC=STATUS ) 

VERIFY- (STATUS) 


RUN 

real, pointer, dimension( : , : , : ) :: imQ => null() 
real, pointer, dimension( : , : , : ) :: exQ => null() 

call MAPL-GetPointer ( IMPORT, imQ, ’Q’, „RC„ ) 
call MAPL-GetPointer ( IMPORT, exQ, ’Q’, „RC„ ) 
exQ = imQ 

In the HISTORY. rc hie, we will need the setting: 

’Q’ , ’ CTMenv ’ , 
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Appendix C: Export State Variables 
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Note that the component names on the list refer to the subcomponents of GOCART. In the HISTORY. rc hie, use GOCART as the component 
who owns each variable on the list. 
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